/**
 *   This file is part of Graph-Tool.
 *
 *   Graph-Tool is free software: you can redistribute it and/or modify
 *   it under the terms of the GNU General Public License as published by
 *   the Free Software Foundation, either version 3 of the License, or
 *   (at your option) any later version.
 *
 *   Graph-Tool is distributed in the hope that it will be useful,
 *   but WITHOUT ANY WARRANTY; without even the implied warranty of
 *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *   GNU General Public License for more details.
 *
 *   You should have received a copy of the GNU General Public License
 *   along with Graph-Tool.  If not, see <http://www.gnu.org/licenses/>.
 */
package graphtool.graphs;

import java.util.Collection;


/**
 * @author a.lunkeit - alunkeit(at)gmail(dot)com
 *
 */
public interface Graph<V, E>
{
  /**
   * Returns the vertices of the graph
   * @return
   */
  public Collection<V> getVertices();
  
  /**
   * Returns the edges of the graph
   * 
   * @return
   */
  public Collection<E> getEdges();
  
  /**
   * Adds a new node to the set of vertices
   * 
   * @param v
   */
  public void addNode( V v ) throws GraphPropertyException;
  
  /**
   * Adds an edge to the set of edges
   * 
   * @param e
   * @param srcV
   * @param targetV
   */
  public void addEdge( E e, V srcV, V targetV ) throws GraphPropertyException;
  
  /**
   * Removes the specified edge from the graph
   * 
   * @param e
   * @param src
   * @param target
   */
  public void removeEdge( E e, V src, V target ) throws GraphPropertyException;
  
  /**
   * Removes a node from the node
   * 
   * @param v
   */
  public void removeNode( V v ) throws GraphPropertyException;
  
  /**
   * Provides the neighbours of the given vertex
   * 
   * @param v
   * @return
   */
  public Collection<V> neighbours( V v );
  
  /**
   * Provides the edges incident to the vertex
   * 
   * @param v
   * @return
   */
  public Collection<E> incidents( V v );
  
  /**
   * Returns the vertex that is connected with the edge starting at vertex v
   * 
   * @param e
   * @param v
   * @return
   */
  public Pair<V, V> getConnected( E e, V v );
  
  /**
   * Returns the end points of the edge
   * 
   * @param e
   * @return
   */
  public Pair<V,V> getEndpoints( E e );
  
  /**
   * 
   * @return
   */
  public int getVertexCount();
  
  /**
   * 
   * @return
   */
  public int getEdgeCount();
  
  /**
   * Tests if the edge is part of the graph
   * 
   * @param e
   * @return
   */
  public boolean containsEdge( E e );
  
  /**
   * Tests if the vertex is part of the graph
   * 
   * @param v
   * @return
   */
  public boolean containsEndpoint( V v );
  
  /**
   * Set the weight of the edge. By default all edge weights are initialized
   * with value 1, this function can be used to change the weight of an edge.
   * 
   * @param e - The edge to set the weight
   * @param weight - The weight of the edge
   */
  public void setEdgeWeight( E e, float weight ) throws GraphPropertyException;
  
  /**
   * Returns the weight of an edge
   * 
   * @param e
   * @return
   * @throws GraphPropertyException
   */
  public float getEdgeWeight( E e ) throws GraphPropertyException;
  
}
